/*
 * This file is part of the Code::Blocks IDE and licensed under the GNU General Public License, version 3
 * http://www.gnu.org/licenses/gpl-3.0.html
 */

#ifndef ENVVARS_COMMON_H
#define ENVVARS_COMMON_H

#include <wx/arrstr.h>
#include <wx/string.h>

class wxCheckListBox;


#if (defined (__WIN32__) || defined (_WIN64)) && !wxCHECK_VERSION(3, 0, 0)
    #define CHECK_LIST_BOX_CLIENT_DATA 0
#else
    #define CHECK_LIST_BOX_CLIENT_DATA 1
#endif

#define EV_DBGLOG nsEnvVars::EnvVarsDebugLog

// ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----

namespace nsEnvVars
{
    //!< separator for envvars in config
    //!< 配置中环境变量的分隔符
  extern const wxString EnvVarsSep;
  //!< name of default envvar set
  //!< 默认环境变量集的名称
  extern const wxString EnvVarsDefault;

  /** Prints a message to C::B's debug log depending on debug activated or not
    * \param msg Message to print at C::B's debug log
    * 根据调试激活与否,将消息打印到C::B的调试日志
    * 参数:msg 要在C::B的调试日志中打印的消息
    */
  void          EnvVarsDebugLog(const wxChar* msg, ...);

  /** Tokenises an envvar string into sub-strings
    * \param str String to tokenise (envvars set format to array string)
    * \return Tokenised envars as array string
    * 将环境变量字符串标记为子字符串
    * 参数:str 要标记的字符串(环境变量将格式设置为数组字符串)
    * 返回值:被环境变量标记的数组字符串
    */
  wxArrayString EnvvarStringTokeniser(const wxString& str);
  /** Returns all envvars sets available
    * \return All envvars sets available in the config
    * 返回所有可用的环境变量集
    * 返回值:配置中可用的所有环境变量集(字符串数组)
    */
  wxArrayString GetEnvvarSetNames();
  /** Returns the name of the currently active set (from config, /active_set)
    * \return Name of the currently active set (from config, /active_set)
    * 返回当前活动集的名称(从配置中,/active_set)
    * 返回值:当前活动集的名称(来自配置,/active_set)
    */
  wxString      GetActiveSetName();
  /** Returns the path to the envvar set in the config by it's name
    * \param set_name Name of the set to query/find in the config
    * \param check_exists Check if the set really exists in the config (error otherwise)
    * \param return_default Return the default envvar set if the set to query has not been found in the config
    * \return Name of the envvar set
    * 返回在配置中按名称设置的环境变量的路径
    * 参数:set_name 要在配置中查询/查找的集合的名称
    * 参数:check_exists 检查配置中是否确实存在该集合(否则出错)
    * 参数:return_default 如果在配置中未找到要查询的集,则返回默认环境变量集
    * 返回值:环境变量集的名称
    */
  wxString      GetSetPathByName(const wxString& set_name,
                                 bool check_exists = true,
                                 bool return_default = true);
  /** Returns the envvars of an envvars set path in the config
    * \param set_path Path to the envvars set in the config to query
    * \return All envvars that belong to the envvar set in the config
    * 返回配置中环境变量集路径的环境变量
    * 参数:set_path 要查询的配置中设置的环境变量的路径
    * 返回值:属于配置中环境变量集的所有环境变量
    */
  wxArrayString GetEnvvarsBySetPath(const wxString& set_path);
  /** Verifies if an envvars set really exists in the config
    * \param set_name Name of the set to query/find in the config
    * \return Has the set been found / does it exist in the config?
    *
    * 验证配置中是否确实存在环境变量集
    * 参数:set_name 要在配置中查询/查找的集合的名称
    * 返回值:集合是否已找到/它是否存在于配置中?
    */
  bool          EnvvarSetExists(const wxString& set_name);
  /** Allows the user to veto overwriting an existing envvar with a new value
    * \param key envvar key to set (overwrite)
    * \param lstEnvVars Pointer to a check-listbox to update (envvar settings dialog)
    * \param sel Selection in the check listbox to update
    * \return Has the user vetoed to update the envvar?
    * 允许用户否决用新值覆盖现有环境变量
    * 参数:key 要设置的环境变量键(覆盖)
    * 参数:lstEnvVars 指向要更新的复选框的指针("环境变量设置"对话框)
    * 参数:sel 在要更新的复选框中选择
    * 返回值:用户是否拒绝更新环境变量？
    */
  bool          EnvvarVetoUI(const wxString& key, wxCheckListBox* lstEnvVars, int sel);
  /** Clears all envvars of a checklist box
    * \param lstEnvVars Pointer to a check-listbox to update (envvar settings dialog)
    * \return Has the check listbox been updated successfully?
    * 清除检查表框的所有环境
    * 参数:lstEnvVars 指向要更新的复选框的指针("环境变量设置"对话框)
    * 返回值:是否已成功更新复选框?
    */
  bool          EnvvarsClearUI(wxCheckListBox* lstEnvVars);
  /** Checks, if an envvar is recursive, like PATH=%PATH%;C:\Folder
    * \param key   envvar to check
    * \param value value of the envvar to check for recursion
    * \return Is this a recursive envvar?
    * 检查环境变量是否是递归的,如PATH=%PATH%;C:\Folder
    * 参数:key 要检查的环境变量
    * 参数:value 要检查递归的环境变量的值
    * 返回值:这是递归环境变量吗?
    *
    */
  bool          EnvvarIsRecursive(const wxString& key, const wxString& value);
  /** Discards an envvar
    * \param key envvar to discard (erase)
    * \return Has the envvar been discarded successfully?
    * environment variables
    * 丢弃环境变量
    * 参数:key 要丢弃的环境变量(擦除)
    * 返回值:环境变量是否已成功丢弃?
    */
  bool          EnvvarDiscard(const wxString& key);
  /** Applies a specific envvar
    * \param key envvar key to set
    * \param value envvar value to set (value of the key)
    * \return Has the envvar been applied successfully?
    * 应用特定的环境变量
    * 参数:key 要设置的环境变量键
    * 参数:value 要设置的环境变量值(键的值)
    * 返回值:环境变量是否已成功应用?
    */
  bool          EnvvarApply(const wxString& key, const wxString& value);
  /** Applies a specific envvar array (and appends (checks) the envvar in a checklist box accordingly)
    * \param envvar Set of 1..n envvars to apply
    * \param lstEnvVars Pointer to a check-listbox to update (envvar settings dialog)
    * \return Have all envvars been applied successfully?
    * 应用特定的环境变量数组(并相应地在检查表框中附加(检查)环境变量)
    * 参数:envvar 要应用的1..n环境变量集
    * 参数:lstEnvVars 指向要更新的复选框的指针("环境变量设置"对话框)
    * 返回值:是否已成功应用所有环境变量?
    *
    */
  bool          EnvvarArrayApply(const wxArrayString& envvar,
                                 wxCheckListBox*      lstEnvVars = NULL);
  /** Applies a specific envvar set from the config (without UI interaction)
    * \param set_name Name of the set to apply (maps to a path in the config)
    * \param even_if_active Apply the envvar set even if it is active (it might have changed!)
    * 应用配置中的特定环境变量集(无UI交互)
    * 参数:set_name 要应用的集的名称(映射到配置中的路径)
    * 参数:even_if_active 应用环境变量集,即使它处于活动状态(它可能已更改!)
    */
  void          EnvvarSetApply(const wxString& set_name, bool even_if_active);
  /** Discards a specific envvar set from the config (without UI interaction)
    * \param set_name envvar set to discard completely
    * 从配置中丢弃特定的环境变量集(无UI交互)
    * 参数:set_name 环境变量设置为完全丢弃
    */
  void          EnvvarSetDiscard(const wxString& set_name);

//环境变量列表框的键值对结构
#if CHECK_LIST_BOX_CLIENT_DATA==1
  struct EnvVariableListClientData : wxClientData
  {
      EnvVariableListClientData(const wxString &_key, const wxString &_value) : key(_key), value(_value) {}
      wxString key, value;
  };
#endif

}// nsEnvVars

#endif // ENVVARS_COMMON_H
